IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/librw/RWGDlist.z/RWGDlist

Text File | 2002-10-03 | 11.7 KB | 331 lines

RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                                  RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWGDlist(type) - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/gdlist.h>



              declare(RWGDlist, type)
          RWGDlist(type) a;




DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
     Class RRRRWWWWGGGGDDDDlllliiiisssstttt((((ttttyyyyppppeeee)))) represents a group of ordered elements of type ttttyyyyppppeeee,
     not accessible by an external key.  Duplicates are allowed.  This class
     is implemented as a doubly-linked list.  Objects of type RRRRWWWWGGGGDDDDlllliiiisssstttt((((ttttyyyyppppeeee))))
     are declared with macros defined in the standard C++ header file
     <<<<ggggeeeennnneeeerrrriiiicccc....hhhh>>>>.  In order to find a particular item within the collection, a
     user-provided global "tester" function is required to test for a "match,"
     definable in any consistent way.  This function should have prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrrFFFFuuuunnnnccccttttiiiioooonnnn(const ttttyyyyppppeeee* c, const void* d);





     The argument cccc is a candidate within the collection to be tested for a
     match.  The argument dddd is for your convenience and will be passed to
     yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrrFFFFuuuunnnnccccttttiiiioooonnnn(((()))).  The function should return TTTTRRRRUUUUEEEE if a "match" is
     found between cccc and dddd.  In order to simplify the documentation below, an
     imaginary typedef

              typedef RWBoolean (*yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr)(const ttttyyyyppppeeee*, const void*);





     has been used for this tester function.

PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
     None

EEEExxxxaaaammmmpppplllleeee
              #include <rw/gdlist.h>
          #include <rw/rstream.h>
          declare(RWGDlist,int)    /* Declare a list of ints */
          main()  {
            RWGDlist(int) list;    // Define a list of ints



                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                                  RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))



            int *ip;
            list.insert(new int(5));   // Insert some ints
            list.insert(new int(7));
            list.insert(new int(1));
            list.prepend(new int(11));
            RWGDlistIterator(int) next(list);
            while(ip = next() )
              cout << *ip << endl;   // Print out the members
            while(!list.isEmpty())
              delete list.get();     // Remove & delete list items
            return 0;
          }


     Program output:

                   11
               5
               7
               1



PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
              RWGDlist(ttttyyyyppppeeee)();


     Construct an empty collection.

              RWGDlist(ttttyyyyppppeeee)(ttttyyyyppppeeee* a);


     Construct a collection with one entry aaaa.

              RWGDlist(ttttyyyyppppeeee)(const RWGDlist(ttttyyyyppppeeee)& a);


     Copy constructor.  A shallow copy of aaaa is made.

AAAAssssssssiiiiggggnnnnmmmmeeeennnntttt OOOOppppeeeerrrraaaattttoooorrrr
              void
          ooooppppeeeerrrraaaattttoooorrrr====(const RWGDlist(ttttyyyyppppeeee)& a);


     Assignment operator.  A shallow copy of aaaa is made.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              ttttyyyyppppeeee****
          aaaappppppppeeeennnndddd(type* a);


     Adds an item to the end of the collection.  Returns nnnniiiillll if the insertion



                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                                  RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))



     was unsuccessful.

              void
          aaaappppppppllllyyyy(void (*ap)(ttttyyyyppppeeee*, void*), void* );


     Visits all the items in the collection in order, from first to last,
     calling the user-provided function pointed to by aaaapppp for each item.  This
     function should have prototype:

              void yyyyoooouuuurrrrAAAAppppppppllllyyyyFFFFuuuunnnnccccttttiiiioooonnnn(ttttyyyyppppeeee**** c, void*);





     and can perform any operation on the object at address cccc.  The last
     argument is useful for passing data to the apply function.

              ttttyyyyppppeeee*&
          aaaatttt(size_t i);
          const ttttyyyyppppeeee*
          aaaatttt(size_t i) const;


     Returns a pointer to the iiiith item in the collection.  The first variant
     can be used as an lvalue, the second cannot.  The index iiii must be between
     zero and the number of items in the collection less one, or an exception
     of type TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.

              void
          cccclllleeeeaaaarrrr();


     Removes all items in the collection.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr t, const void* d) const;


     Returns TTTTRRRRUUUUEEEE if the collection contains an item for which the user-
     defined function pointed to by tttt finds a match with dddd.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssssRRRReeeeffffeeeerrrreeeennnncccceeee(const ttttyyyyppppeeee* e) const;


     Returns TTTTRRRRUUUUEEEE if the collection contains an item with the address eeee....

              size_t
          eeeennnnttttrrrriiiieeeessss() const;




                                                                        PPPPaaaaggggeeee 3333






RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                                  RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))



     Returns the number of items in the collection.

              ttttyyyyppppeeee*
          ffffiiiinnnndddd(yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr t, const void* d) const;


     Returns the first item in the collection for which the user-provided
     function pointed to by tttt finds a match with dddd, or nnnniiiillll if no item is
     found.

              ttttyyyyppppeeee*
          ffffiiiinnnnddddRRRReeeeffffeeeerrrreeeennnncccceeee(const type* e) const;


     Returns the first item in the collection with the address eeee, or nnnniiiillll if no
     item is found.

              ttttyyyyppppeeee*
          ffffiiiirrrrsssstttt() const;


     Returns the first item of the collection.

              ttttyyyyppppeeee*
          ggggeeeetttt();


     Returns and rrrreeeemmmmoooovvvveeeessss the first item of the collection.

              ttttyyyyppppeeee*
          iiiinnnnsssseeeerrrrtttt(ttttyyyyppppeeee* e);


     Adds an item to the end of the collection and returns it.  Returns nnnniiiillll if
     the insertion was unsuccessful.

              void
          iiiinnnnsssseeeerrrrttttAAAAtttt(size_t indx, ttttyyyyppppeeee**** e);


     Adds a new item to the collection at position iiiinnnnddddxxxx.  The item previously
     at position iiii is moved to iiii++++1111, eeeettttcccc.  The index iiiinnnnddddxxxx must be between 0 and
     the number of items in the collection, or an exception of type TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX
     will be thrown.

              RWBoolean
          iiiissssEEEEmmmmppppttttyyyy() const;


     Returns TTTTRRRRUUUUEEEE if the collection is empty, otherwise FFFFAAAALLLLSSSSEEEE.





                                                                        PPPPaaaaggggeeee 4444






RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))                                                  RRRRWWWWGGGGDDDDlllliiiisssstttt((((3333CCCC++++++++))))



              ttttyyyyppppeeee*
          llllaaaasssstttt() const;


     Returns the last item of the collection.

              size_t
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffff(yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr t, const void* d) const;


     Returns the number of occurrences in the collection for which the user-
     provided function pointed to by tttt finds a match with dddd.

              size_t
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffffRRRReeeeffffeeeerrrreeeennnncccceeee(const ttttyyyyppppeeee* e) const;


     Returns the number of items in the collection with the address eeee....

              ttttyyyyppppeeee*
          prepend(type* a);


     Adds an item to the beginning of the collection.  Returns nnnniiiillll if the
     insertion was unsuccessful.

              ttttyyyyppppeeee*
          rrrreeeemmmmoooovvvveeee(yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr t, const void* d);


     Removes and returns the first item from the collection for which the
     user-provided function pointed to by tttt finds a match with dddd, or returns
     nnnniiiillll if no item is found.

              ttttyyyyppppeeee*
          rrrreeeemmmmoooovvvveeeeRRRReeeeffffeeeerrrreeeennnncccceeee(const type* e);


     Removes and returns the first item from the collection with the address
     eeee, or returns nnnniiiillll if no item is found.















                                                                        PPPPaaaaggggeeee 5555